CUBE CONNECT Edition Help

Control statements

Most of the standard Matrix program statements are valid in the Distribution program, and a few additional ones are available.

Since the Distribution program is a subset of the Matrix program, it is assumed that the user is familiar with the Matrix-program control statement set. Only the differences between the Matrix and Distribution control statements are included in this section. For descriptions of other control statements see Control Statements under the Matrix program.

Matrix program statements not allowed in the Distribution program: + RENUMBER

Distribution program statements not in the Matrix program:

Distribution program keywords not in the Matrix program:

GRAVITY

Performs a standard gravity model. Keywords include:

This statement is used to have the program compute a distribution based upon traditional gravity model formulation for a single purpose. It is more efficient than using multiple COMP statements to formulate the same process.

GRAVITY Keywords

  • FFACTORS |SN| - Specifies the expression that results in the friction factor that a gravity equation expects. Normally, this would be the name of the lookup table that contains the friction factors that correspond to the values that are to be extracted from LOS. In this statement, no arguments should be used with the lookup name. The lookup table is expected to be in the form shown in the Examples. The lookup arguments will be automatically set to the value from the LOS matrix and the PURPOSE number. See LOOKUP for hints about using Lookups to obtain friction factors.

  • KFACTORS |S| - Specifies the matrix that contains the K-factor values for each I-J distribution. The value MUST be either a MW[#] or an MI.#.name/#.

  • LOS |S| - Specifies the matrix that contains the level-of-service values for each I-J distribution. The value MUST be either a MW[#] or an MI.#.name/#.

  • LOSRANGE |R| - Optional. Specifies the range of LOS values that are valid for use in the distribution process. If an I-J values is less than the first value or greater than the second value, there will be no distribution between for I-J. This keyword must be followed by a pair of numbers separated by a dash. The first number must be 0, or greater, and the second value must be greater than the first. Default range is 0 - 999999.

  • PURPOSE |I| - Specifies which purpose this is calculation to: the results will be stored in MW[PURPOSE].

PURPOSE, LOS, and FFACTORS must be specified.

Example 

lookup fail=12000,1,0, list=n, file=tstff1, name=ff,
lookup[1]=1,result=2,
lookup[2]=1,result=3,
lookup[3]=1,result=4,

PARAMETERS

Sets general parameters. Keywords include:

In addition to the standard Matrix-program parameters, the parameters described here may also be specified.

PARAMETERS keywords

  • MATOEVERY - |K?| - Switch that can be used to force the program to write output matrices for every iteration, instead of waiting until the last iteration. This causes the program to run somewhat longer for each iteration, but may preclude the program from having to run another iteration to obtain the output matrices once convergence is reached. Since the program does not know that a particular iteration will be the final one until after it completes the iteration, it normally does not write matrices for the iteration. This saves a considerable amount of computer time for larger systems. But, it does force another processing iteration to write the matrices once it has determined that this is the last iteration. If it is anticipated that there will be many iterations to reach convergence, it is probably better to set this switch false. If it is anticipated that the process will involve only a few iterations, it is probably better to set this switch true.

  • MAXITERS - |KI| - Specifies the maximum number of iterations to perform. If the MAXRMSE criterion is met, the number of iterations actually performed could be less than this value. The default is 3, and the max is 99. If the model converges in fewer iterations, one more iteration will be run (with the same values as the converging iteration) so that the MATO matrices will be written.

  • MAXRMSE - |KR| - Specifies the cutoff criteria. If the highest RMSE (for any purpose) exceeds this value, automatic cutoff is not triggered. Conversely, if all the purpose RMSEs are less than this value, automatic cutoff is triggered. The default is 10, and the minimum is 0.0001.

  • ZONES - |KI| - Specifies the highest zone number to process. If the number of zones can not be ascertained from the project file or from any binary input matrices, ZONES must be provided, or the value will default to 100. If present, this value controls the application. Normally, there will be an input matrix file, so this keyword should not be required.

REPORT

Specifies Matrix program reports. Keywords and subkeywords include:

REPORT Keywords

  • ACOMP - |KIP| - Requests that the comparison of Estimated vs. Desired attractions be reported for the specified purposes. The report is in a format that is similar the MARGINS report. The values are reported as nearest integers (without decimal places). Only the purposes specified by the keyword are reported. If the values for ACOMP are followed by ITERATIONS, then those ACOMP purposes will be printed only during the iterations specified. If there are no ITERATIONS specified, the report will be printed for every iteration (could be quite voluminous). In ACOMP reports, zero values are printed with – and a printed value of “0” means there is a fractional value present for the cell (the fractions are not printed in the report).

  • ACOMP - ITERATIONS - |IP| - Specifies the iterations for which the prior ACOMP purposes reports are to be printed. If no ITERATIONS follow ACOMP values, the reports will be printed for all iterations. If at least one value is equal to, or exceeds, the PARAMETERS MAXITERS, the reports will be printed for the last iteration (no matter how it is determined: parameter or convergence).

Example 

REPORT ACOMP=1-3,5 ITERATIONS=5,10,99 ; specified purposes and iterations
REPORT ACOMP=6 ; for all iterations

SETPA

Establishes base productions and attractions. Keywords include:

The SETPA statement is required; if it is not included, the program will fatally terminate.

The statement defines to the program how the desired productions and attractions are to be obtained, and how many purposes are to be processed. There should be a P[]= and A[]= expression for every purpose beginning with 1 and continuing, monotonically, until all purposes are defined. The highest index encountered establishes the number of purposes.

If there are any holes in the purpose scheme, the program will issue a warning statement. The total of the As should match the total of the Ps for each purpose. If the totals differ by more than five percent of the P total, a message is issued. If the totals differ by any amount, the As are scaled so that the A total will match the P total.

The Ps and As are computed from the expressions that are supplied. In most cases, the expression will simply point to a ZDATI file variable. Complex expressions are allowed, but the use of any variables in the expression could cause unpredictable results. In a purpose where the Ps and As are the same for each zone, (NonHomeBased is a typical example), it is acceptable to set the Ps, and then set the As equal to the Ps. The SETPA expressions are computed in the order in which they appear in the control stream, and they are computed only one time – prior to the first iteration. For each array, the expression is solved in a loop of J=1-Zones, and the results are stored in the A[n][J] or P[n][J] cells. A and P may not have a zone index in the SETPA statement.

If the same purpose is referenced more than one time (this is acceptable), the subsequent values will replace the prior values. Duplication of purposes might be helpful if values for different zones for a purpose are to be obtained from different sources, or if different INCLUDE/EXCLUDE filters are to be used (separate SETPA statements must be used for different filters).

SETPA Keywords

  • A - |NV| - Expression that is solved to set the attractions for the indexed purpose.

  • EXCLUDE - |IP| - Processed the same as EXCLUDE on COMP statements. If it is used, the loop will not be processed for any zones in the list. EXCLUDE filtering follows any INCLUDE filtering.

  • INCLUDE - |IP| - Processed the same as INCLUDE on COMP statements. If it is used, the loop will not be processed for any zones not in the list. INCLUDE filtering precedes any EXCLUDE zones.

  • P - |NV| - Expression that is solved to set the productions for the indexed purpose.

Example 

SETPA INCLUDE=1-500, ; internal zone data only
P[1]=zi.1.p1, A[1]=zi.1.a1,
P[2]=zi.1.p2, A[2]=zi.1.a2,
P[3]=zi.1.nhb, A[3]=P[3],
P[4]=zi.2.cnt, A[4]=10 ; equal attraction for all zones
SETPA EXCLUDE=1-500, ; get only external data
P[1]=zi.1.p1, A[1]=zi.2.cnt, ; merges with prior SETPA
P[5]=sqrt(A[3]), A[5]=A[1]+A[2]+A[3] ; weird, but will work
Parent topic: Distribution